CD ROM Paradise Collection 4/CD ROM Paradise Collection 4 1995 Nov.iso/system/chang412.zip/CHANGE.DOC

Text File | 1994-12-14 | 18KB | 368 lines

CHANGE.DOC
12/14/94

Program written by:
                        Bruce Guthrie
                        Room H-4885
                        U.S. Dept of Commerce/ESA/OBA/BSISD
                        Washington, D.C. 20230

                        [phone]

You may freely copy and re-distribute this program; however, the U.S.
Department of Commerce neither guarantees nor assures compatibility of the
program with all computer software or hardware.

Foreign users:  Please provide an Internet e-mail address in all correspondence
or and just e-mail your problems to me at [e-mail]


The CHANGE.EXE program allows you to make changes in binary or text files of any
size.  Features:

  * Can handle files of any size provided you have enough room on your disk
    to hold a copy of resulting file
  * Can be used to change text files or binary files
  * Can be used to remove trailing spaces from a file
  * Can specify different lengths for the input strings and the output strings
  * Can specify that the changes only be done in lines that include a certain
    character string.  This selection string can be case-insensitive
  * Can handle up to 30 change requests at a time
  * Can specify the input/output strings as ASCII characters, hexadecimal
    values, or as decimal values
  * Handles the changes fairly quickly
  * Can either replace the original file with the resulting file or else
    create a new changed file (using /Noutfile specification)
  * Changes can be verified before they are made
  * Changes can be entered in any of the following ways:
      - from the command line (one TO/FROM pair allowed)
      - interactively (one TO/FROM pair allowed)
      - from a controlfile (up to 30 TO/FROM pairs allowed)
  * Boolean operators can be used if the TO/FROM pair is specified from the
    command line (e.g. CHANGE TEST.TXT /FROM One /TO Many /IN Apples OR Oranges

The CHANGE program does not support standard wildcards for the input file names.
You can use the DOS FOR command to handle this if you'd like:

        FOR %a IN (A*.TXT C*.DOC) DO CHANGE %a /FROM "One" /TO "Another"


The CHANGE.INI file:

CHANGE will read a CHANGE.INI file if one is found.  (You can specify a
different file name if desired.) The file is an ASCII text file that can be
created maintained by hand.  The file can consist or one or more command line
parameters (only those that begin with a "/"), one statement per line.

The file can also contain comments which are blank lines or any line beginning
with:
        ;    (semi-colon)
        :    (colon)
        '    (quote)

CHANGE looks for the initialization file in your default subdirectory first.  It
then searches for it in the subdirectory where the executable was and then goes
through your DOS path.

Passing in "/INULL" skips loading the INI file.  This saves some execution time
as the program does not need to search your path for the file.  Do *NOT* use
"/-I" for this or you will turn off case sensitivity in the search.


CONFIGWS.EXE:

In addition to using the CHANGE.INI file, you can permanently change some
defaults within CHANGE.EXE by using the CONFIGWS.EXE program.  CONFIGWS.EXE is
not included in the CHANGE distribution package but previous versions can
typically be used with CHANGE if desired.  (The same CONFIGWS.EXE program can
be used to path a number of Wayne Software programs.) If CONFIGWS can't patch
the executable, it will notify you of this before altering anything.

CONFIGWS.EXE allows you to set the following defaults:

        Reverse criteria: /V or /-V
        Case insensitive: /I or /-I

When setting options, the program will process defaults in the following order:
  (1) CONFIGWS.EXE-settable settings
  (2) CHANGE.INI settings
  (3) command-line settings

The *last* settings encountered win.



Syntax:

    CHANGE infile [ /Cctlfile | /FROM string /TO string [ /IN search ] ]
      [ /LINES { line1-line2 | line1 linect } ... ] [ /V | /-V ] [ /I | /-I ]
      [ /Noutfile [ /OVERWRITE | /-OVERWRITE | /OVERASK ] ]
      [ /Iinitfile ] [ /Fflagfile ] [ /Ttempfile ] [ /TRIM | /-TRIM ]
      [ /BINARY | /TEXT ] [ /VERIFY | /-VERIFY ] [ /Q ] [ /? | /?&H ]

where:

"infile" can include a drive and path designation.  It is the file name you
want changed.  Unless you specify a /Noutfile parameter, the infile will be
overwritten by this program.

"/Cctlfile" contains the change commands to make.  If a ctlfile is not provided
and a FROM/TO option is not specified, the routine will prompt you for one FROM
(what's the text you want to change from; case is significant unless /I is
specified), TO (what's the text you want to change to; case is always
significant), and IN (what string the line must be contain before the change is
applied; case is always significant unless /I is specified) request.  If a
ctlfile is used, you can specify up to 30 change requests at a time.  Each line
of the change file should consist of records of one of four record types:

  * blank lines or those beginning with semi-colons are treated as comments.
  * lines beginning with "-F" or "-f" provide FROM options.
  * lines beginning with "-T" or "-t" provide TO options.
  * lines beginning with "-I" or "-i" provide IN options.  These are optional;
    if not provided, all lines will be searched for the FROM string.  Any
    IN request forces /TEXT mode to be invoked

If more than one set of FROM/TO/IN records is provided, the -F specification
(for a control file) must precede the others.  Each option is local to a given
FROM/TO/IN specification.  For example:

        ; Sample control file
        -FPRINT
        -TPrinting
        -I"
        -fUSING
        -tused

contains two FROM/TO/IN specifications.  "PRINT" will be changed to "Printing"
in any line with a double quote.  "USING" will be changed to "used" in all
lines; no -I option is applied for the second FROM/TO/IN specification.

The FROM/TO/IN specifications can include any text characters.  They can also
contain ASCII codes, created either using the Alt key in combination with the
numeric keypad (e.g.  Alt-228 to get a Sigma character) or else by embedding a
hexadecimal code (in the form &Hxx) or a decimal code (in the form \nnn) in the
text.  You can get a table of hexadecimal codes at the end of this documentation
or by saying "CHANGE /?&H".  For example, to change a double carriage
return/line feed to a single carriage return/line feed, you could say:

        -F&H0D0A0D0A
        -T&H0D0A


(Note that the above example would require you to use the /BINARY option as well
since it extends beyond line boundaries.)

If you need to follow a hexadecimal specification with normal text characters,
follow the hex spec with one space (which CHANGE will ignore).  For example,

        -F&H0c Hi!
        -T&H0d0a Bye!

To remove a string entirely, use the -T without anything after it or use
"-TNULL" or "/TO NULL" from the command line.

"/FROM string /TO string [ /IN search ]" allows you to specify the from/to
parameters on the control line.  Quotation marks are required around the strings
if they include spaces or special characters.  Note that certain characters
cannot be passed in because DOS considers them special characters and steals
them first.  This includes ">" and "|" characters.  You'll have to use the
control file or the interactive mode in this case or else use the &Hxx or \nnn
conventions.  "search" is further described below.  To eliminate a string
entirely, use "/TO NULL" or use the control file instead.

"/Iinitfile" says to read an initialization file with the file name "initfile".
The file specification *must* contain a period.  If no drive or path information
is specified, the program will search for initfile beginning in your default
subdirectory and then going throughout your DOS path.  The use of an
initialization file is optional.  Initially defaults to "/ICHANGE.INI".
"/INULL" says to skip loading the initialization file.

"/LINES line1-line2" says to restrict the search to lines between line numbers
line1 and line2 inclusive.  You can have multiple line requests in any order
such as "/LINES 1-10 90-100 30-50".  The routine skips all lines after the
largest line number is encountered.  Defaults to "/LINES 1-9999999".

"/LINES line1 linect" says to restrict the search to lines beginning with line1
and continuing for a total of linect lines.  So "/LINES 10 20" is actually the
same as "/LINES 10-29".

"/V" says to find those items that do NOT match the specification.

"/-V" is the opposite of /V and is typically the default; CONFIGWS-able.

"/I" says to make it a case-insensitive search.

"/-I" is the opposite of /I and is typically the default; CONFIGWS-able.

"/Noutfile" is the name of the new file to create.  If a /Noutfile is not
specified, the source document (infile) will be replaced by the changed file.

"/OVERWRITE" says to write over the outfile (if requested) if it exists
already.

"/-OVERWRITE" says to abort if the outfile exists already.

"/OVERASK" says to ask if the outfile exists already.  This is the default.


"/Fflagfile" is the name of a file to contain all changed lines.  This allows
you to see what the lines were changed to for verification purposes.  This
option automatically invokes /TEXT.

"/Ttempfile" is the name of the temporary file to create.  The actual changes
are written to a temp file and then the source file is replaced with the temp
file is everything works and there were actually changes to be found in the
source document.  By default, the temp file is written to the same path as the
input file.  The temporary file will be as big as the final file is.  If you
don't have enough room for it to be on your source disk, specify another
temporary file name with a different path (e.g. "/TG:\TEMP.TXT").

"/TRIM" says to remove trailing spaces from the end of each line.  Automatically
forces you into TEXT mode.

"/-TRIM" is the opposite of /TRIM and is the default.

"/TEXT" puts you into TEXT mode.  TEXT mode means that all data in the file are
read in and processed as separate text records.  Alternatively, the file can be
processed in BINARY mode in which case the file is read in in 8,000-byte blocks.
BINARY mode is quicker and is required for EXE and COM files.  TEXT mode
presents some information like the number of lines in your file and is
*required* if you specify any of the following options:

        * an IN (or -I) request
        * /LINES
        * /Fflagfile
        * /TRIM
        * /VERIFY

"/BINARY" is the opposite of TEXT mode.  It's faster than TEXT and is the
default for CHANGE.  It is overridden if you specify certain options listed
above.

"/VERIFY" says to prompt you before changing any lines.  You are asked to
confirm that you in fact want to make each change requested.  Automatically
forces you into TEXT mode.

"/-VERIFY" is the opposite of /VERIFY and is the default.

"/Q" turns off the line-by-line status messages.

"/?" or "/HELP" or "HELP" shows you the syntax for the command.

"/?&H" gives you a hexadecimal and decimal conversion table.



For search, the syntax is:
  [ ( ]... search_item [ boolean [ ( ]... search_item [ ) ]...] [ ) ]...
where:
  ( and )     are used to group items
  search_item is shown below
  boolean     is AND, OR, or XOR (NOT is included with search_item)

for search_item, the syntax is:
  [ NOT ]  "string" [ column ]
where:
  NOT         is obvious
  string      the string to search; the quotation marks are typically not
              required unless the string contains a space or a reserved word
  column      is the column in which the string must be found.

So, let's cover some examples:

        CHANGE TEST.TXT /FROM Apple /TO Banana /IN "Bugs Bunny" OR "Elmer Fudd"

Changes the string "Apple" to "Banana" in any lines that have either the text
"Bugs Bunny" or "Elmer Fudd" in them.

        CHANGE TEST2.TXT /FROM Bugs /TO Bunny /IN (Apples or Oranges) AND NOT
           Pears /LINES=1-1000 /COLS=1/5

Changes "Bugs" to "Bunny" in the first thousand lines of TEST2.TXT.  The line
itself must contain the words "Apples" or "Oranges" in them and any lines are
ignored that contain "Pears".  Note that the quotes around the search words are
not required unless the words include spaces or unless they could be confused
with some other keywords.  "CHANGE TEST3.TXT /FROM Bugs /TO Bunny /IN OR OR AND"
might cause the program to get confused since "OR" and "AND", which you want to
look for as also keywords.

        CHANGE /I TEST.TXT /FROM One /TO Many /IN "Bugs Bunny" AND Martians

This changes "One" to "Many" is any lines that contain both "Bugs Bunny" and
"Martians".  The search is case-insensitive so lines with either "BUGS BUNNY"
and "Bugs Bunny" will be changed.

NOTE:  THIS EXTENDED SEARCHING CAPABILITY IS SUPPORTED ONLY FOR /IN REQUESTS
MADE FROM THE COMMAND LINE.  IT IS NOT SUPPORTED IN EITHER THE CTLFILE OR IN THE
INTERACTIVE TO/FROM SELECTION MODE.


Return codes:

CHANGE returns the following ERRORLEVEL codes:
        0 = no problems, changes made
        1 = no problems, nothing found to change
      253 = routine aborted early
      254 = internal problems
      255 = syntax problems, file not found, or /? requested


Decimal and hexadecimal codes:
  e.g. "\066\097\116" and "&H426174" both are "Bat"
+---------------------------------------------------------------------------
| dec  hex chr | dec  hex chr | dec  hex chr | dec  hex chr | dec  hex chr |
+--------------+--------------+--------------+--------------+--------------+
| \000 &H00 nul| \052 &H34 4  | \104 &H68 h  | \156 &H9C £  | \208 &HD0 ╨  |
| \001 &H01 
  | \053 &H35 5  | \105 &H69 i  | \157 &H9D ¥  | \209 &HD1 ╤  |
| \002 &H02   | \054 &H36 6  | \106 &H6A j  | \158 &H9E ₧  | \210 &HD2 ╥  |
| \003 &H03   | \055 &H37 7  | \107 &H6B k  | \159 &H9F ƒ  | \211 &HD3 ╙  |
| \004 &H04   | \056 &H38 8  | \108 &H6C l  | \160 &HA0 á  | \212 &HD4 ╘  |
| \005 &H05   | \057 &H39 9  | \109 &H6D m  | \161 &HA1 í  | \213 &HD5 ╒  |
| \006 &H06   | \058 &H3A :  | \110 &H6E n  | \162 &HA2 ó  | \214 &HD6 ╓  |
| \007 &H07 bel| \059 &H3B ;  | \111 &H6F o  | \163 &HA3 ú  | \215 &HD7 ╫  |
| \008 &H08 bs | \060 &H3C <  | \112 &H70 p  | \164 &HA4 ñ  | \216 &HD8 ╪  |
| \009 &H09 tab| \061 &H3D =  | \113 &H71 q  | \165 &HA5 Ñ  | \217 &HD9 ┘  |
| \010 &H0A lf | \062 &H3E >  | \114 &H72 r  | \166 &HA6 ª  | \218 &HDA ┌  |
| \011 &H0B vt | \063 &H3F ?  | \115 &H73 s  | \167 &HA7 º  | \219 &HDB █  |
| \012 &H0C pg | \064 &H40 @  | \116 &H74 t  | \168 &HA8 ¿  | \220 &HDC ▄  |
| \013 &H0D cr | \065 &H41 A  | \117 &H75 u  | \169 &HA9 ⌐  | \221 &HDD ▌  |
| \014 &H0E   | \066 &H42 B  | \118 &H76 v  | \170 &HAA ¬  | \222 &HDE ▐  |
| \015 &H0F   | \067 &H43 C  | \119 &H77 w  | \171 &HAB ½  | \223 &HDF ▀  |
| \016 &H10   | \068 &H44 D  | \120 &H78 x  | \172 &HAC ¼  | \224 &HE0 α  |
| \017 &H11   | \069 &H45 E  | \121 &H79 y  | \173 &HAD ¡  | \225 &HE1 ß  |
| \018 &H12   | \070 &H46 F  | \122 &H7A z  | \174 &HAE «  | \226 &HE2 Γ  |
| \019 &H13   | \071 &H47 G  | \123 &H7B {  | \175 &HAF »  | \227 &HE3 π  |
| \020 &H14   | \072 &H48 H  | \124 &H7C |  | \176 &HB0 ░  | \228 &HE4 Σ  |
| \021 &H15   | \073 &H49 I  | \125 &H7D }  | \177 &HB1 ▒  | \229 &HE5 σ  |
| \022 &H16   | \074 &H4A J  | \126 &H7E ~  | \178 &HB2 ▓  | \230 &HE6 µ  |
| \023 &H17   | \075 &H4B K  | \127 &H7F   | \179 &HB3 │  | \231 &HE7 τ  |
| \024 &H18   | \076 &H4C L  | \128 &H80 Ç  | \180 &HB4 ┤  | \232 &HE8 Φ  |
| \025 &H19   | \077 &H4D M  | \129 &H81 ü  | \181 &HB5 ╡  | \233 &HE9 Θ  |
| \026 &H1A eof| \078 &H4E N  | \130 &H82 é  | \182 &HB6 ╢  | \234 &HEA Ω  |
| \027 &H1B esc| \079 &H4F O  | \131 &H83 â  | \183 &HB7 ╖  | \235 &HEB δ  |
| \028 &H1C   | \080 &H50 P  | \132 &H84 ä  | \184 &HB8 ╕  | \236 &HEC ∞  |
| \029 &H1D ???| \081 &H51 Q  | \133 &H85 à  | \185 &HB9 ╣  | \237 &HED φ  |
| \030 &H1E ???| \082 &H52 R  | \134 &H86 å  | \186 &HBA ║  | \238 &HEE ε  |
| \031 &H1F ???| \083 &H53 S  | \135 &H87 ç  | \187 &HBB ╗  | \239 &HEF ∩  |
| \032 &H20    | \084 &H54 T  | \136 &H88 ê  | \188 &HBC ╝  | \240 &HF0 ≡  |
| \033 &H21 !  | \085 &H55 U  | \137 &H89 ë  | \189 &HBD ╜  | \241 &HF1 ±  |
| \034 &H22 "  | \086 &H56 V  | \138 &H8A è  | \190 &HBE ╛  | \242 &HF2 ≥  |
| \035 &H23 #  | \087 &H57 W  | \139 &H8B ï  | \191 &HBF ┐  | \243 &HF3 ≤  |
| \036 &H24 $  | \088 &H58 X  | \140 &H8C î  | \192 &HC0 └  | \244 &HF4 ⌠  |
| \037 &H25 %  | \089 &H59 Y  | \141 &H8D ì  | \193 &HC1 ┴  | \245 &HF5 ⌡  |
| \038 &H26 &  | \090 &H5A Z  | \142 &H8E Ä  | \194 &HC2 ┬  | \246 &HF6 ÷  |
| \039 &H27 '  | \091 &H5B [  | \143 &H8F Å  | \195 &HC3 ├  | \247 &HF7 ≈  |
| \040 &H28 (  | \092 &H5C \  | \144 &H90 É  | \196 &HC4 ─  | \248 &HF8 °  |
| \041 &H29 )  | \093 &H5D ]  | \145 &H91 æ  | \197 &HC5 ┼  | \249 &HF9 ∙  |
| \042 &H2A *  | \094 &H5E ^  | \146 &H92 Æ  | \198 &HC6 ╞  | \250 &HFA ·  |
| \043 &H2B +  | \095 &H5F _  | \147 &H93 ô  | \199 &HC7 ╟  | \251 &HFB √  |
| \044 &H2C ,  | \096 &H60 `  | \148 &H94 ö  | \200 &HC8 ╚  | \252 &HFC ⁿ  |
| \045 &H2D -  | \097 &H61 a  | \149 &H95 ò  | \201 &HC9 ╔  | \253 &HFD ²  |
| \046 &H2E .  | \098 &H62 b  | \150 &H96 û  | \202 &HCA ╩  | \254 &HFE ■  |
| \047 &H2F /  | \099 &H63 c  | \151 &H97 ù  | \203 &HCB ╦  | \255 &HFF    |
| \048 &H30 0  | \100 &H64 d  | \152 &H98 ÿ  | \204 &HCC ╠  |              |
| \049 &H31 1  | \101 &H65 e  | \153 &H99 Ö  | \205 &HCD ═  |              |
| \050 &H32 2  | \102 &H66 f  | \154 &H9A Ü  | \206 &HCE ╬  |              |
| \051 &H33 3  | \103 &H67 g  | \155 &H9B ¢  | \207 &HCF ╧  |              |
+--------------+--------------+--------------+--------------+--------------+